2025 m. rugpjūčio 21 d.Lietuvių

Išsami JavaScript dekoratorių analizė: sintaksė, metaduomenų programavimo atvejai, gerosios praktikos ir poveikis kodo palaikomumui. Su praktiniais pavyzdžiais.

JavaScript Dekoratoriai: Metaduomenų Programavimo Įgyvendinimas

JavaScript dekoratoriai yra galinga funkcija, leidžianti deklaratyviu ir pakartotinai naudojamu būdu pridėti metaduomenis ir keisti klasių, metodų, savybių ir parametrų elgseną. Tai yra 3-iosios stadijos pasiūlymas ECMAScript standartų procese ir plačiai naudojamas su TypeScript, kuris turi savo (šiek tiek kitokį) įgyvendinimą. Šiame straipsnyje pateikiama išsami JavaScript dekoratorių apžvalga, sutelkiant dėmesį į jų vaidmenį metaduomenų programavime ir iliustruojant jų naudojimą praktiniais pavyzdžiais.

Kas yra JavaScript Dekoratoriai?

Dekoratoriai yra projektavimo šablonas, kuris pagerina arba modifikuoja objekto funkcionalumą, nekeičiant jo struktūros. JavaScript kalboje dekoratoriai yra specialios rūšies deklaracijos, kurias galima pridėti prie klasių, metodų, prieigos metodų, savybių ar parametrų. Jie naudoja @ simbolį, po kurio eina funkcija, kuri bus įvykdyta, kai dekoruojamas elementas bus apibrėžtas.

Galvokite apie dekoratorius kaip apie funkcijas, kurios kaip įvestį priima dekoruojamą elementą ir grąžina modifikuotą to elemento versiją arba atlieka tam tikrą šalutinį poveikį, pagrįstą juo. Tai suteikia švarų ir elegantišką būdą pridėti funkcionalumą, tiesiogiai nekeičiant originalios klasės ar funkcijos.

Pagrindinės sąvokos:

Dekoratoriaus funkcija: Funkcija, prieš kurią eina @ simbolis. Ji gauna informaciją apie dekoruojamą elementą ir gali jį modifikuoti.
Dekoruojamas elementas: Klasė, metodas, prieigos metodas, savybė ar parametras, kuris yra dekoruojamas.
Metaduomenys: Duomenys, apibūdinantys duomenis. Dekoratoriai dažnai naudojami susieti metaduomenis su kodo elementais.

Sintaksė ir Struktūra

Pagrindinė dekoratoriaus sintaksė yra tokia:

@decorator
class MyClass {
  // Class members
}

Čia @decorator yra dekoratoriaus funkcija, o MyClass yra dekoruojama klasė. Dekoratoriaus funkcija yra iškviečiama, kai klasė yra apibrėžiama, ir gali pasiekti bei modifikuoti klasės apibrėžimą.

Dekoratoriai taip pat gali priimti argumentus, kurie perduodami pačiai dekoratoriaus funkcijai:

@loggable(true, "Custom Message")
class MyClass {
  // Class members
}

Šiuo atveju loggable yra dekoratoriaus fabriko funkcija, kuri priima argumentus ir grąžina tikrąją dekoratoriaus funkciją. Tai leidžia sukurti lankstesnius ir konfigūruojamus dekoratorius.

Dekoratorių Tipai

Yra įvairių tipų dekoratorių, priklausomai nuo to, ką jie dekoruoja:

Klasių dekoratoriai: Taikomi klasėms.
Metodų dekoratoriai: Taikomi metodams klasės viduje.
Prieigos metodų dekoratoriai: Taikomi getter ir setter prieigos metodams.
Savybių dekoratoriai: Taikomi klasės savybėms.
Parametrų dekoratoriai: Taikomi metodo parametrams.

Klasių Dekoratoriai

Klasių dekoratoriai naudojami modifikuoti arba pagerinti klasės elgseną. Jie kaip argumentą gauna klasės konstruktorių ir gali grąžinti naują konstruktorių, kuris pakeis originalųjį. Tai leidžia pridėti funkcionalumą, pvz., registravimą, priklausomybių injekciją ar būsenos valdymą.

Pavyzdys:

function loggable(constructor: Function) {
  console.log("Klasė " + constructor.name + " buvo sukurta.");
}

@loggable
class User {
  name: string;

  constructor(name: string) {
    this.name = name;
  }
}

const user = new User("Alice"); // Išvestis: Klasė User buvo sukurta.

Šiame pavyzdyje loggable dekoratorius registruoja pranešimą konsolėje kiekvieną kartą, kai sukuriamas naujas User klasės egzempliorius. Tai gali būti naudinga derinant ar stebint programos veikimą.

Metodų Dekoratoriai

Metodų dekoratoriai naudojami modifikuoti metodo elgseną klasės viduje. Jie gauna šiuos argumentus:

target: Klasės prototipas.
propertyKey: Metodo pavadinimas.
descriptor: Metodo savybės deskriptorius.

Deskriptorius leidžia pasiekti ir modifikuoti metodo elgseną, pvz., apgaubti jį papildoma logika arba visiškai jį iš naujo apibrėžti.

Pavyzdys:

function logMethod(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const originalMethod = descriptor.value;

  descriptor.value = function (...args: any[]) {
    console.log(`Kviečiamas metodas ${propertyKey} su argumentais: ${args}`);
    const result = originalMethod.apply(this, args);
    console.log(`Metodas ${propertyKey} grąžino: ${result}`);
    return result;
  };
  return descriptor;
}

class Calculator {
  @logMethod
  add(a: number, b: number): number {
    return a + b;
  }
}

const calculator = new Calculator();
const sum = calculator.add(5, 3); // Išveda registracijos įrašus apie metodo iškvietimą ir grąžinamą reikšmę

Šiame pavyzdyje logMethod dekoratorius registruoja metodo argumentus ir grąžinamą reikšmę. Tai gali būti naudinga derinant ir stebint našumą.

Prieigos Metodų Dekoratoriai

Prieigos metodų dekoratoriai yra panašūs į metodų dekoratorius, bet taikomi getter ir setter prieigos metodams. Jie gauna tuos pačius argumentus kaip ir metodų dekoratoriai ir leidžia modifikuoti prieigos metodo elgseną.

Pavyzdys:

function validate(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const originalSet = descriptor.set;

  descriptor.set = function (value: any) {
    if (value < 0) {
      throw new Error("Reikšmė turi būti neneigiama.");
    }
    originalSet.call(this, value);
  };
}

class Temperature {
  private _celsius: number;

  constructor(celsius: number) {
    this._celsius = celsius;
  }

  @validate
  set celsius(value: number) {
    this._celsius = value;
  }

  get celsius(): number {
    return this._celsius;
  }
}

const temperature = new Temperature(25);
temperature.celsius = 30; // Teisinga
// temperature.celsius = -10; // Išmeta klaidą

Šiame pavyzdyje validate dekoratorius užtikrina, kad temperatūros reikšmė būtų neneigiama. Tai gali būti naudinga užtikrinant duomenų vientisumą.

Savybių Dekoratoriai

Savybių dekoratoriai naudojami modifikuoti klasės savybės elgseną. Jie gauna šiuos argumentus:

target: Klasės prototipas (egzemplioriaus savybėms) arba klasės konstruktorius (statinėms savybėms).
propertyKey: Savybės pavadinimas.

Savybių dekoratoriai gali būti naudojami apibrėžti metaduomenis arba modifikuoti savybės deskriptorių.

Pavyzdys:

function readonly(target: any, propertyKey: string) {
  Object.defineProperty(target, propertyKey, {
    writable: false,
  });
}

class Configuration {
  @readonly
  apiUrl: string = "https://api.example.com";
}

const config = new Configuration();
// config.apiUrl = "https://newapi.example.com"; // Griežtuoju režimu išmeta klaidą

Šiame pavyzdyje readonly dekoratorius paverčia apiUrl savybę tik skaitoma, neleidžiant jos modifikuoti po inicializacijos. Tai gali būti naudinga apibrėžiant nekintamas konfigūracijos reikšmes.

Parametrų Dekoratoriai

Parametrų dekoratoriai naudojami modifikuoti metodo parametro elgseną. Jie gauna šiuos argumentus:

target: Klasės prototipas (egzemplioriaus metodams) arba klasės konstruktorius (statiniams metodams).
propertyKey: Metodo pavadinimas.
parameterIndex: Parametro indeksas metodo parametrų sąraše.

Parametrų dekoratoriai naudojami rečiau nei kitų tipų dekoratoriai, tačiau jie gali būti naudingi tikrinant įvesties parametrus ar injektuojant priklausomybes.

Pavyzdys:

function required(target: any, propertyKey: string, parameterIndex: number) {
  const existingRequiredParameters: number[] = Reflect.getOwnMetadata(propertyKey, target, "required") || [];
  existingRequiredParameters.push(parameterIndex);
  Reflect.defineMetadata(propertyKey, existingRequiredParameters, target, "required");
}

function validateMethod(target: any, propertyName: string, descriptor: PropertyDescriptor) {
  let method = descriptor.value!;

  descriptor.value = function () {
    let requiredParameters: number[] = Reflect.getOwnMetadata(propertyName, target, "required");
    if (requiredParameters) {
      for (let parameterIndex of requiredParameters) {
        if (arguments[parameterIndex] === null || arguments[parameterIndex] === undefined) {
          throw new Error(`Trūksta privalomo argumento indekse ${parameterIndex}`);
        }
      }
    }

    return method.apply(this, arguments);
  };
}


class ArticleService {
  create(
    @required title: string,
    @required content: string
  ): void {
    console.log(`Kuriamas straipsnis su pavadinimu: ${title} ir turiniu: ${content}`);
  }
}

const service = new ArticleService();
// service.create("My Article", null); // Išmeta klaidą
service.create("My Article", "Article Content"); // Teisinga

Šiame pavyzdyje required dekoratorius pažymi parametrus kaip privalomus, o validateMethod dekoratorius užtikrina, kad šie parametrai nebūtų null arba undefined. Tai gali būti naudinga užtikrinant metodo įvesties patikrinimą.

Metaduomenų Programavimas su Dekoratoriais

Vienas galingiausių dekoratorių panaudojimo atvejų yra metaduomenų programavimas. Metaduomenys yra duomenys apie duomenis. Programavimo kontekste tai yra duomenys, apibūdinantys jūsų kodo struktūrą, elgseną ir tikslą. Dekoratoriai suteikia švarų ir deklaratyvų būdą susieti metaduomenis su klasėmis, metodais, savybėmis ir parametrais.

Reflect Metadata API

Reflect Metadata API yra standartinė API, leidžianti saugoti ir gauti metaduomenis, susietus su objektais. Ji suteikia šias funkcijas:

Reflect.defineMetadata(key, value, target, propertyKey): Apibrėžia metaduomenis konkrečiai objekto savybei.
Reflect.getMetadata(key, target, propertyKey): Gauna metaduomenis konkrečiai objekto savybei.
Reflect.hasMetadata(key, target, propertyKey): Patikrina, ar egzistuoja metaduomenys konkrečiai objekto savybei.
Reflect.deleteMetadata(key, target, propertyKey): Ištrina metaduomenis konkrečiai objekto savybei.

Galite naudoti šias funkcijas kartu su dekoratoriais, kad susietumėte metaduomenis su savo kodo elementais.

Pavyzdys: Metaduomenų Apibrėžimas ir Gavimas

import 'reflect-metadata';

const logKey = "log";

function log(message: string) {
  return function (target: any, key: string, descriptor: PropertyDescriptor) {
    Reflect.defineMetadata(logKey, message, target, key);

    const originalMethod = descriptor.value;
    descriptor.value = function (...args: any[]) {
      console.log(Reflect.getMetadata(logKey, target, key));
      const result = originalMethod.apply(this, args);
      return result;
    }

    return descriptor;
  }
}

class Example {
  @log("Vykdomas metodas")
  myMethod(arg: string): string {
    return `Metodas iškviestas su ${arg}`;
  }
}

const example = new Example();
example.myMethod("Hello"); // Išvestis: Vykdomas metodas, Metodas iškviestas su Hello

Šiame pavyzdyje log dekoratorius naudoja Reflect Metadata API, kad susietų registracijos pranešimą su myMethod metodu. Kai metodas yra iškviečiamas, dekoratorius gauna ir registruoja pranešimą konsolėje.

Metaduomenų Programavimo Panaudojimo Atvejai

Metaduomenų programavimas su dekoratoriais turi daug praktinių pritaikymų, įskaitant:

Serializavimas ir Deserializavimas: Anotuokite savybes metaduomenimis, kad kontroliuotumėte, kaip jos yra serializuojamos ar deserializuojamos į/iš JSON ar kitų formatų. Tai gali būti naudinga dirbant su duomenimis iš išorinių API ar duomenų bazių, ypač paskirstytose sistemose, reikalaujančiose duomenų transformacijos tarp skirtingų platformų (pvz., konvertuojant datų formatus tarp skirtingų regioninių standartų). Įsivaizduokite el. prekybos platformą, dirbančią su tarptautiniais pristatymo adresais, kurioje galėtumėte naudoti metaduomenis, kad nurodytumėte teisingą adreso formatą ir patvirtinimo taisykles kiekvienai šaliai.
Priklausomybių injekcija: Naudokite metaduomenis, kad identifikuotumėte priklausomybes, kurias reikia injektuoti į klasę. Tai supaprastina priklausomybių valdymą ir skatina laisvą susiejimą. Apsvarstykite mikroservisų architektūrą, kur paslaugos priklauso viena nuo kitos. Dekoratoriai ir metaduomenys gali palengvinti dinamišką paslaugų klientų injekciją remiantis konfigūracija, leidžiant lengviau keisti mastelį ir užtikrinti atsparumą gedimams.
Patvirtinimas (validacija): Apibrėžkite patvirtinimo taisykles kaip metaduomenis ir naudokite dekoratorius automatiniam duomenų patvirtinimui. Tai užtikrina duomenų vientisumą ir sumažina pasikartojančio kodo kiekį. Pavyzdžiui, pasaulinė finansų programa turi atitikti įvairius regioninius finansinius reglamentus. Metaduomenys galėtų apibrėžti valiutų formatų, mokesčių skaičiavimo ir operacijų limitų patvirtinimo taisykles, atsižvelgiant į vartotojo buvimo vietą, užtikrinant atitiktį vietiniams įstatymams.
Maršrutizavimas ir Tarpinė Programinė Įranga (Middleware): Naudokite metaduomenis, kad apibrėžtumėte maršrutus ir tarpinę programinę įrangą interneto programoms. Tai supaprastina jūsų programos konfigūraciją ir padaro ją lengviau prižiūrimą. Pasauliniu mastu paskirstytas turinio pristatymo tinklas (CDN) galėtų naudoti metaduomenis, kad apibrėžtų podėliavimo politiką ir maršrutizavimo taisykles, atsižvelgiant į turinio tipą ir vartotojo buvimo vietą, optimizuojant našumą ir mažinant delsą vartotojams visame pasaulyje.
Autorizacija ir Autentifikacija: Susiekite vaidmenis, leidimus ir autentifikacijos reikalavimus su metodais ir klasėmis, palengvindami deklaratyvias saugumo politikas. Įsivaizduokite tarptautinę korporaciją su darbuotojais skirtinguose skyriuose ir vietovėse. Dekoratoriai gali apibrėžti prieigos kontrolės taisykles, pagrįstas vartotojo vaidmeniu, skyriumi ir vieta, užtikrinant, kad tik įgalioti darbuotojai galėtų pasiekti jautrius duomenis ir funkcionalumą.

Gerosios Praktikos

Naudodami JavaScript dekoratorius, atsižvelkite į šias gerasias praktikas:

Laikykite dekoratorius paprastus: Dekoratoriai turėtų būti sutelkti ir atlikti vieną, gerai apibrėžtą užduotį. Venkite sudėtingos logikos dekoratoriuose, kad išlaikytumėte skaitomumą ir palaikomumą.
Naudokite dekoratorių fabrikus: Naudokite dekoratorių fabrikus, kad leistumėte konfigūruojamus dekoratorius. Tai padaro jūsų dekoratorius lankstesnius ir pakartotinai naudojamus.
Venkite šalutinių poveikių: Dekoratoriai pirmiausia turėtų sutelkti dėmesį į dekoruojamo elemento modifikavimą arba metaduomenų susiejimą su juo. Venkite sudėtingų šalutinių poveikių dekoratoriuose, kurie galėtų apsunkinti jūsų kodo supratimą ir derinimą.
Naudokite TypeScript: TypeScript suteikia puikų palaikymą dekoratoriams, įskaitant tipų tikrinimą ir „IntelliSense“. Naudojant TypeScript galite anksčiau pagauti klaidas ir pagerinti savo kūrimo patirtį.
Dokumentuokite savo dekoratorius: Aiškiai dokumentuokite savo dekoratorius, paaiškindami jų paskirtį ir kaip juos reikėtų naudoti. Tai palengvina kitiems kūrėjams suprasti ir teisingai naudoti jūsų dekoratorius.
Atsižvelkite į našumą: Nors dekoratoriai yra galingi, jie taip pat gali paveikti našumą. Būkite atidūs savo dekoratorių našumo pasekmėms, ypač našumui jautriose programose.

Internacionalizacijos su Dekoratoriais Pavyzdžiai

Dekoratoriai gali padėti internacionalizacijai (i18n) ir lokalizacijai (l10n), susiejant konkrečiai vietovei skirtus duomenis ir elgseną su kodo komponentais:

Pavyzdys: Lokalizuotas Datos Formavimas

import 'reflect-metadata';

interface DateFormatOptions {
  locale: string;
  options?: Intl.DateTimeFormatOptions;
}

const dateFormatKey = 'dateFormat';

function formatDate(options: DateFormatOptions) {
  return function(target: any, propertyKey: string) {
    Reflect.defineMetadata(dateFormatKey, options, target, propertyKey);
  };
}

class Event {
  @formatDate({ locale: 'fr-FR', options: { year: 'numeric', month: 'long', day: 'numeric' } })
  startDate: Date;

  constructor(startDate: Date) {
    this.startDate = startDate;
  }

  getFormattedStartDate(): string {
    const options: DateFormatOptions = Reflect.getMetadata(dateFormatKey, Object.getPrototypeOf(this), 'startDate');
    return this.startDate.toLocaleDateString(options.locale, options.options);
  }
}

const event = new Event(new Date());
console.log(event.getFormattedStartDate()); // Išveda datą prancūzišku formatu

Pavyzdys: Valiutos Formavimas pagal Vartotojo Vietovę

import 'reflect-metadata';

interface CurrencyFormatOptions {
  locale: string;
  currency: string;
}

const currencyFormatKey = 'currencyFormat';

function formatCurrency(options: CurrencyFormatOptions) {
  return function(target: any, propertyKey: string) {
    Reflect.defineMetadata(currencyFormatKey, options, target, propertyKey);
  };
}

class Product {
  @formatCurrency({ locale: 'de-DE', currency: 'EUR' })
  price: number;

  constructor(price: number) {
    this.price = price;
  }

  getFormattedPrice(): string {
    const options: CurrencyFormatOptions = Reflect.getMetadata(currencyFormatKey, Object.getPrototypeOf(this), 'price');
    return this.price.toLocaleString(options.locale, { style: 'currency', currency: options.currency });
  }
}

const product = new Product(99.99);
console.log(product.getFormattedPrice()); // Išveda kainą vokiškame euro formate

Ateities Perspektyvos

JavaScript dekoratoriai yra besivystanti funkcija, o standartas vis dar kuriamas. Kai kurios ateities perspektyvos apima:

Standartizavimas: ECMAScript dekoratorių standartas vis dar rengiamas. Standartui vystantis, gali keistis dekoratorių sintaksė ir elgsena.
Našumo optimizavimas: Kai dekoratoriai taps plačiau naudojami, atsiras poreikis optimizuoti našumą, siekiant užtikrinti, kad jie neigiamai nepaveiktų programos veikimo.
Įrankių palaikymas: Pagerintas įrankių palaikymas dekoratoriams, pvz., IDE integracija ir derinimo įrankiai, palengvins kūrėjams efektyviai naudoti dekoratorius.

Išvada

JavaScript dekoratoriai yra galingas įrankis metaduomenų programavimui ir jūsų kodo elgsenos gerinimui. Naudodami dekoratorius, galite pridėti funkcionalumą švariu, deklaratyviu ir pakartotinai naudojamu būdu. Tai lemia lengviau prižiūrimą, testuojamą ir keičiamo mastelio kodą. Suprasti skirtingus dekoratorių tipus ir kaip juos efektyviai naudoti yra būtina šiuolaikiniam JavaScript kūrimui. Dekoratoriai, ypač derinami su Reflect Metadata API, atveria daugybę galimybių, nuo priklausomybių injekcijos ir patvirtinimo iki serializavimo ir maršrutizavimo, todėl jūsų kodas tampa išraiškingesnis ir lengviau valdomas.